{smcl}

{cmd:help warofatt}
{hline}


{title:Title}

{p 4 8}{help warofatt} - Estimate a split population duration estimator corresponding to 
	a war of attrition model.


{title:Syntax}

{p 8 12}{cmd:warofatt} {it:{help depvar}} [{it:{help indvars}}] [if] [in], [{cmdab:tstarv:alues}({it:{help numlist}}) 
	{cmdab:tstarmi:n}(#) {cmdab:tstarma:x}(#) {cmdab:pr:obss}({it:{help indvars:indvars_pr}}) {cmdab:iterate}(#) 
	{cmdab:savel:oglikelihood}({it:{help filename}}) {cmdab:plotl:oglikelihood} 
	{cmdab:grsavel:oglikelihood}({it:{help filename}}) {cmdab:ml:maxoptions}(string) {cmdab:ploth:azard}
	{cmdab:grsaveh:azard}({it:{help filename}}) {cmdab:st:artvalues} {cmdab:rob:ust} {cmdab:cl:uster}({it:clustvar}) 
	{cmdab:l:evel}(#) * ]

{title:Description}

{p 0 4}{cmd:warofatt} estimates the split population duration estimator corresponding to a 
	continuous time war of attrition model described in Boehmke, Dion, and Shipan (2020). The 
	underlying war of attrition model (e.g., Kreps and Wilson 1982) involves two players, 
	each with two possible types: strong or weak. 
	Contests involving at least one weak player produce an increasing hazard with an endogenous
	stopping point, t*. These are estimated via a truncated Weibull model. Contests with two 
	strong players have a flat hazard at zero with a point mass at the end of the game (time T).
	We operationalize these with a standard Weibull hazard. {cmd:warofatt} estimates the 
	parameters of these two duration processes, the mixture rate between them, and the endogenous 
	stopping point t*. Covariates may be included for the truncated Weibull and the logit mixture
	components. It estimates t* by finding the maximum likelihood estimates for the other 
	parameters when t* is held constant, repeating this process for possible values of t*, and
	then reporting the results that produce the largest final log-likelihood.

{title:Options}

{p 4 8}{cmdab:tstarv:alues}({it:{help numlist}}) allows the user to provide a list of time points to
	evaluate as candidate values for t*. The estimator is run at all candidate values and the
	one that produces the largest final log-likelihood is reported. The default is to run it 
	for all observed values of the dependent variable.

{p 4 8}{cmdab:tstarmi:n}(#) If {cmdab:tstarvalues} is not specified, the estimator will use all	
	observed values of the dependent variable as candidate values for t*. {cmd:tstarmin} indicates 
	that values less than # be ignored. This can be helpful in data sets with many distinct
	values of the dependent variable or when are convergence issues with small values, which can 
	arise since observations below t* represents a mixture of the two disitrbutions that may be
	difficult to estimate with few observations.

{p 4 8}{cmdab:tstarma:x}(#) Analogous to {cmd:tstarmin}, except that it excludes values of the
	dependent variable larger than than # as candidate values of t*. This can save time since
	the likelihood typically becomes constant once t* is sufficiently large that the probability
	of all observations in the truncated Weibull distribution failing reaches one. 

{p 4 8}{cmdab:pr:obss}({it:indvars_pr}) allows the user to include covariates in the logit mixture
	equation. If nto specified, {cmd:warofatt} assumes a constant mixture probability. This
	equation predicts the probability that a given observation involves two strong players. 

{p 4 8}{cmdab:st:artvalues} requests that {cmd:warofatt} generate starting values for the estimation
	process. It does so by estimating a Weibull model for values of the dependent variable 
	less than t* and another Weibull model for values greater than t* (dropping to an exponential 
	for the latter if the Weibull doesn't converge). 

{p 4 8}{cmdab:iterate}(#) allows the user to set the maximum number of iterations before estimation
	terminates. If nto specified the default value is used - see {it:{help maximize}} on setting
	this value.

{p 4 8}{cmdab:ml:maxoptions}(string) This allows the user to pass additional 
	{help ml##ml_noninteract_descript:noninteractive} ml maximize options that may not be properly 
	parsed by {help mlopts}, such as {cmd:init()} or {cmd:search()}. 

{p 4 8}{cmdab:savel:oglikelihood}({it:{help filename}}[, {it:{help save##save_options:save_options}}]) 
	saves the final log-likelihood values for all candidate values of t* examined in the estimation 
	into a file. It does not replace the data currently open. 

{p 4 8}{cmdab:plotl:oglikelihood} creates a graph of the final log-likelihood values for all candidate 
	values of t*. Desired {help twoway_options} options may specified as additional options to the
	{cmd:warofatt} command. Note that {cmd:plotloglikelihood} and {cmd:plothazard} may not both
	be specified.

{p 4 8}{cmdab:grsavel:oglikelihood}({it:{help filename}}[, {cmd:asis} {cmd:replace}]) saves a graph of 
	the final log-likelihood values for all candidate values of t* to a file. It requires specificying 
	{cmd:plotloglikelihood}. See {help saving_option} for details. 

{p 4 8}{cmdab:ploth:azard} creates a graph of the predicted hazard functions from the final estimates. 
	If covariates are included, the hazard is generated based only on the intercepts. Desired 
	{help twoway_options} options may specified as additional options to the {cmd:warofatt} command. 
	Note that {cmd:plothazard} and {cmd:plotloglikelihood} may not both be specified.

{p 4 8}{cmdab:grsaveh:azard}({it:{help filename}}[, {it:{help save##save_options:save_options}}]) 
	saves the predicted hazard values into a file. It does not replace the data currently open. 

{p 4 8}{cmdab:rob:ust} requests a Huber/White/sandwich estimator for the variance-covariance matrix.
	See {help vce_option} for details on the {cmd:robust} option. 

{p 4 8}{cmdab:cl:uster}({it:clustvar}) specifies that the standard errors allow for intragroup correlation.
	See {help vce_option} for details on the {cmd:cluster} option. 
	
{title:Notes}

{p 4 8} 1. {cmd:warofatt} estimates a duration model intended to capture the salient features of
	the length of contests in a continuous-time war of attrition model as in Kreps and
	Wilson (1982). These contests are played between two players with one of two types: strong
	(S) or weak (W). There are therefore four types of contests: SS, SW, WS, and WW. It
	is assumed that types are private information and are not know by the opposing player or by 
	the researcher. Dion, Boehmke, MacMillan, and Shipan (2016) derive the hazard functions for these 
	four different types of contests and group them to generate a mixture over two duration processes. 
	One group (SW, WS, and WW) features an increasing hazard with an endogenous stopping time while 
	the other (SS) involves a point mass at the end game. The estimator is designed to capture the 
	salient features of the predicted durations -- it does not correspond exactly to
	the functional form derived from the model itself -- and features the following four 
	components. 
	
{p 8 12} a. Durations of contests involving at least one weak player all have an increasing hazard
	as does their weighted average. Since weak type all exit before the endogenous stopping point
	t*, the distribution has a finite upper bound to be estimated. We model the duration
	of these contests with a truncated Weibull, which allows for an increasing hazard 
	(or, contrary to the theory, a flat or dereasing hazard) and has an upper bound at the 
	truncation point. Covariates may be included since the parameters of the war of attrition
	model affect the shape of this distribution. 
	
{p 8 12} b. Durations of contests involving two strong players are modeled with a regular Weibull	
	distribution as there is no truncation. Boehmke, Dion, and Shipan (2020) show that
	this distribution can be derived as an average over heterogeneous fixed end points across
	contests (e.g., from a uniform distribution of end points). Covariates may not be included
	since the war of attriation model parameters do not predict variation within this equation. 
	
{p 8 12} c. The mixture equation corresponds to a logit that predicts the probability that a given
	contest includes two strong players. Covariates may be included since the parameters of the 
	war of attrition model affect the probablility of contest types.

{p 8 12} d. The endogeneous end point for weak players is represented by t*, the truncation point
	for the truncated Weibull. This is not estimated simultaneously with the other equations.
	Rather, each round of the model sets of value of t* to hold fixed while estimating the 
	parameters of the other equations. This process is then repeated for a set of candidate
	values for t* and the results that produce the largest log-likelihood are reported as the
	final estimates. The default is to use all observed values of the duration outcome of
	interest as candidate values, but the user can select any values they want using the 
	various options. 
	
{p 4 8} 2. There are two considerations for estimation that we address in the paper and incorporate	
	into the code here. 

{p 8 12} a. The ability to estimate t* depends on the realized duration outcomes in the 
	data set employed. In particular it helps to have observations that fail on or near the 
	true value of t*. The estimator will still pick the value of t* that maximizes the final
	log-likelihood. 

{p 8 12} b. The likelihood may become flat when t* reaches sufficiently large values. In particular, 
	this happens when the c.d.f. of the nontruncated Weibull that is modified to create the truncated 
	Weibull distribution reaches one. In that case increases in t* will not affect the likelihood 
	since all observations from the Weibull for weak contests will have failed with probability one 
	even without the truncation adjustment. When this flat region of the likelihood is the maximum 
	we select the results from the smallest value of t* from this region. This is why {cmd: warofatt}
	reports the value of the nontruncated version of the truncated Weibull cdf at t*. 

{p 4 8} 3. When estimating for all requested values of t*, {cmd:warofatt} reports on the results for each
	corresponding model. Those that produce a return code of 0 are indicated by a . whereas those  
	with a different return code are indicated by an {red:x}.

{p 4 8} 4. The current implementation of {cmd:warofatt} does not allow for right censoring in the
	observed data. The likelihood that accounts for that is reported in Boehmke, Dion, and 
	Shipan's (2020) appendix, and we plan to incorporate it into a subsequent release. 

{p 4 8} 5. The war of attrition estimator has some similarities with cure models, but differs in 
	important ways. Both involve a mixture over two populations. But in a cure model one
	population will never fail whereas in the war of attrition model all observations will 
	end, just at different rates. Further, the war of attrition requires and estimates the 
	endogenous stopping point, t*, which does not exist for cure models. 
	

{title:Example}

{p 4 8}{inp:. warofatt days, iterate(100)}{p_end}

{p 4 8}{inp:. warofatt days, iterate(100) startvalues difficult plotloglikelihood scheme(s1mono) ylabel(#5, grid)}{p_end}

{p 4 8}{inp:. warofatt days, tstarmin(4) tstarmax(30) iterate(50) plothazard robust}{p_end}

{p 4 8}{inp:. warofatt days, tstarvalues(5/20) iterate(50) saveloglik(loglikelihood, replace)}{p_end}

{p 4 8}{inp:. warofatt days yesbinder unclearbinder, startvalues iterate(50) difficult plothazard grsavehazard(hazard, replace)}{p_end}

{p 4 8}{inp:. warofatt days yesbinder unclearbinder, probss(yesbinder unclearbinder post1975) startvalues iterate(50) difficult robust}{p_end}

{title:References}

{p 4 4}Frederick J. Boehmke, Douglas Dion, and Charles R. Shipan. N.d. "A Duration 
Estimator for a Continuous Time War of Attrition Game." Political Science Research 
and Methods} (forthcoming).

{p 4 4}Dion, Douglas; Frederick J. Boehmke; William MacMillan; and Charles R. Shipan.  
2016. "The Filibuster as a War of Attrition." The Journal of Law and Economics 589 (3): 
569–595.

{p 4 4}Kreps, David M. and Robert Wilson. 1982. "Reputation and Imperfect Information." 
Journal of Economic Theory 27(2): 253-279.

{title:Author}

    Frederick J. Boehmke
    University of Iowa
    Department of Political Science
    341 Schaeffer Hall
    Iowa City, IA 52242
    frederick-boehmke@uiowa.edu
    http://www.fredboehmke.net
    
{title:Acknowledgements}

{p 0 4}This program is the product of a collaborative research effort with Doug Dion, William MacMillan, 
	and Chuck Shipan. All three are absolved from any Stata programming sins committed here.
    {p_end}

    
